\hypertarget{DynamicArray_8h}{
\section{Source/DynamicArray.h File Reference}
\label{DynamicArray_8h}\index{Source/DynamicArray.h@{Source/DynamicArray.h}}
}
Functions to manipulate dynamic arrays.  


{\tt \#include $<$stdlib.h$>$}\par
{\tt \#include $<$string.h$>$}\par
{\tt \#include $<$errno.h$>$}\par


Include dependency graph for DynamicArray.h:\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=108pt]{DynamicArray_8h__incl}
\end{center}
\end{figure}


This graph shows which files directly or indirectly include this file:\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=79pt]{DynamicArray_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{structdynarray}{D\_\-Array}
\begin{CompactList}\small\item\em A dynamic array. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
D\_\-Array \hyperlink{DynamicArray_8h_6c4c7892b9506cb872054cba92b6efc1}{NewArray} (unsigned int len)
\item 
int \hyperlink{DynamicArray_8h_084f37f851882993e9c18eba4e18d2fb}{FreeArray} (D\_\-Array array)
\item 
int \hyperlink{DynamicArray_8h_7f276e507d614f8e77f193d37dc561d7}{AppendElement} (D\_\-Array array, void $\ast$element)
\item 
int \hyperlink{DynamicArray_8h_27e7ccab2f61c0cf440f1449b1330928}{InsertElement} (D\_\-Array array, unsigned int n, void $\ast$element)
\item 
int \hyperlink{DynamicArray_8h_c1e57a137b52e78045cb6a029f8b0bf7}{RemoveElement} (D\_\-Array array, unsigned int n)
\item 
int \hyperlink{DynamicArray_8h_fa79a315bde67685f9fc5916481d6187}{SetElement} (D\_\-Array array, unsigned int n, void $\ast$element)
\item 
void $\ast$ \hyperlink{DynamicArray_8h_73251fbd5ec9966d578588f13e52c3ab}{GetElement} (D\_\-Array array, unsigned int n)
\item 
unsigned int \hyperlink{DynamicArray_8h_732834609b39534b9959caca8f365606}{GetLength} (D\_\-Array array)
\end{CompactItemize}


\subsection{Detailed Description}
Functions to manipulate dynamic arrays. 

\begin{Desc}
\item[Author:]Stephen Smith\end{Desc}
\hypertarget{Vector_8h_Description}{}\subsection{Description}\label{Vector_8h_Description}
Functions to manipulate dynamic arrays.

In these dynamic arrays, the elements are not copied: pointers to them are. If you wish to store a copy of something, you must copy it yourself. Storing things allocated on the stack is also likely to cause problems.

These arrays are zero-indexed. 

Definition in file \hyperlink{DynamicArray_8h-source}{DynamicArray.h}.

\subsection{Function Documentation}
\hypertarget{DynamicArray_8h_7f276e507d614f8e77f193d37dc561d7}{
\index{DynamicArray.h@{DynamicArray.h}!AppendElement@{AppendElement}}
\index{AppendElement@{AppendElement}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{AppendElement}]{\setlength{\rightskip}{0pt plus 5cm}int AppendElement (D\_\-Array {\em array}, \/  void $\ast$ {\em element})}}
\label{DynamicArray_8h_7f276e507d614f8e77f193d37dc561d7}


Append an element to a dynamic array. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to operate on \item[{\em element}]a pointer to the element to append\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -errno on failure \end{Desc}


Definition at line 56 of file DynamicArray.c.

\begin{Code}\begin{verbatim}57 {
58 
59   /* Allocate space for the new element pointer, if we need to, or die
60      on failure, indicating why. */
61   if( array -> max_length <= array -> length )
62     {
63 
64       if( !( array -> array = realloc( array -> array , 
65                        sizeof( void * ) * 
66                        ( array -> length + 1 ) ) ) )
67     return( -errno ) ;
68 
69       array -> max_length++ ;
70 
71     }
72 
73   /* Copy the pointer */
74   array -> array[ array -> length ] = element ;
75   /* Store the new length */
76   array -> length++ ;
77 
78   /* Success, so return so */
79   return( 0 ) ;
80 
81 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_084f37f851882993e9c18eba4e18d2fb}{
\index{DynamicArray.h@{DynamicArray.h}!FreeArray@{FreeArray}}
\index{FreeArray@{FreeArray}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{FreeArray}]{\setlength{\rightskip}{0pt plus 5cm}int FreeArray (D\_\-Array {\em array})}}
\label{DynamicArray_8h_084f37f851882993e9c18eba4e18d2fb}


Free a dynamic array. Note that this does not free the elements of the array.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to free\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]always 0, until free(3) decides to report errors, rather than die in flames \end{Desc}


Definition at line 40 of file DynamicArray.c.

\begin{Code}\begin{verbatim}41 {
42 
43   /* Free the element pointers */
44   free( array -> array ) ;
45   /* Free the struct */
46   free( array ) ;
47 
48   /* This function only returns int for symmetry with everything else:
49      free(3) never indicates errors, so we can't either. */
50   return( 0 ) ;
51 
52 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_73251fbd5ec9966d578588f13e52c3ab}{
\index{DynamicArray.h@{DynamicArray.h}!GetElement@{GetElement}}
\index{GetElement@{GetElement}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{GetElement}]{\setlength{\rightskip}{0pt plus 5cm}void$\ast$ GetElement (D\_\-Array {\em array}, \/  unsigned int {\em n})}}
\label{DynamicArray_8h_73251fbd5ec9966d578588f13e52c3ab}


Return an element of a dynamic array

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to operate on \item[{\em n}]the index of the element to return\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a pointer to the element asked for, or NULL if it doesn't exist (e.g. if the element asked for is beyond the end of the array \end{Desc}


Definition at line 180 of file DynamicArray.c.

\begin{Code}\begin{verbatim}181 {
182 
183   if( n >= array -> length )
184     return( NULL ) ;
185   else
186     return array -> array[ n ] ;
187 
188 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_732834609b39534b9959caca8f365606}{
\index{DynamicArray.h@{DynamicArray.h}!GetLength@{GetLength}}
\index{GetLength@{GetLength}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{GetLength}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int GetLength (D\_\-Array {\em array})}}
\label{DynamicArray_8h_732834609b39534b9959caca8f365606}


Return the length of a dynamic array

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to find the length of\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the length of the array \end{Desc}


Definition at line 191 of file DynamicArray.c.

\begin{Code}\begin{verbatim}192 {
193 
194   return( array -> length ) ;
195 
196 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_27e7ccab2f61c0cf440f1449b1330928}{
\index{DynamicArray.h@{DynamicArray.h}!InsertElement@{InsertElement}}
\index{InsertElement@{InsertElement}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{InsertElement}]{\setlength{\rightskip}{0pt plus 5cm}int InsertElement (D\_\-Array {\em array}, \/  unsigned int {\em n}, \/  void $\ast$ {\em element})}}
\label{DynamicArray_8h_27e7ccab2f61c0cf440f1449b1330928}


Insert an element to a dynamic array.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to operate on \item[{\em n}]the position to insert the element \item[{\em element}]a pointer to the element to append\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -errno on failure \end{Desc}


Definition at line 84 of file DynamicArray.c.

\begin{Code}\begin{verbatim}85 {
86 
87   /* We will copy the element pointers into this new array, inserting
88      the new one at the right moment. */
89   void **newarray = NULL ;
90 
91   /* Allocate the new array, or die on failure */
92   if( !( newarray = malloc( ( array -> length + 1 ) * sizeof( void * ) ) ) )
93     return( -errno ) ;
94 
95   /* Copy the part below where the new element will be */
96   memcpy( newarray , array -> array , n * sizeof( void * ) ) ;
97 
98   /* Copy the new element */
99   newarray[ n ] = element ;
100 
101   /* Copy the rest */
102   memcpy( newarray + n + 1 , 
103       array -> array + n , 
104       ( array -> length - n ) * sizeof( void * ) ) ;
105 
106   /* Free the old array, and copy the new one in its place */
107   free( array -> array ) ;
108   array -> array = newarray ;
109 
110   /* Update the length of the array */
111   array -> max_length = array -> length++ ;
112 
113   /* Success, so return so */
114   return( 0 ) ;
115 
116 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_6c4c7892b9506cb872054cba92b6efc1}{
\index{DynamicArray.h@{DynamicArray.h}!NewArray@{NewArray}}
\index{NewArray@{NewArray}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{NewArray}]{\setlength{\rightskip}{0pt plus 5cm}D\_\-Array NewArray (unsigned int {\em len})}}
\label{DynamicArray_8h_6c4c7892b9506cb872054cba92b6efc1}


Make a new dynamic array

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em len}]initial length of the array\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the new array \end{Desc}


Definition at line 12 of file DynamicArray.c.

\begin{Code}\begin{verbatim}13 {
14 
15   D_Array retval = NULL ;
16 
17   /* Allocate the struct holding our housekeeping information, and die
18      on failure */
19   if( !( retval = malloc( sizeof( struct dynarray ) ) ) )
20     return( NULL ) ;
21 
22   /* Allocate the initial element pointers, and die on failure */
23   if( !( retval -> array = malloc( sizeof( void * ) * len ) ) )
24     {
25 
26       free( retval ) ;
27       return( NULL ) ;
28 
29     }
30 
31   /* Store the length of the array */
32   retval -> max_length = retval -> length = len ;
33 
34   /* Return what we have just allocated */
35   return( retval ) ;
36 
37 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_c1e57a137b52e78045cb6a029f8b0bf7}{
\index{DynamicArray.h@{DynamicArray.h}!RemoveElement@{RemoveElement}}
\index{RemoveElement@{RemoveElement}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{RemoveElement}]{\setlength{\rightskip}{0pt plus 5cm}int RemoveElement (D\_\-Array {\em array}, \/  unsigned int {\em n})}}
\label{DynamicArray_8h_c1e57a137b52e78045cb6a029f8b0bf7}


Remove an element from a dynamic array

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to operate on \item[{\em n}]the index of the element to remove\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -errno on failure \end{Desc}


Definition at line 119 of file DynamicArray.c.

\begin{Code}\begin{verbatim}120 {
121 
122   /* We will copy the element pointers into this new array, except the
123      one we don't want. */
124   void **newarray = NULL ;
125 
126   /* See if the element being removed is beyond the end of the array:
127      if so, do nothing. */
128   if( n >= array -> length )
129     return( 0 ) ;
130 
131   /* Allocate the new array, or die on failure */
132   if( !( newarray = malloc( ( array -> length ) * sizeof( void * ) ) ) )
133     return( -errno ) ;
134 
135   /* Copy the part below the element to be removed */
136   memcpy( newarray , array -> array , n * sizeof( void * ) ) ;
137 
138   /* Ignore the element to be removed, and copy the rest */
139   memcpy( newarray + n , 
140       array -> array + n + 1 , 
141       ( array -> length - ( n + 1 ) ) * sizeof( void * ) ) ;
142 
143   /* Free the old array, and copy the new one in its place */
144   free( array -> array ) ;
145   array -> array = newarray ;
146 
147   /* Store the reduced length */
148   array -> max_length = array -> length-- ;
149 
150   /* Success, so return so */
151   return( 0 ) ;
152 
153 }
\end{verbatim}
\end{Code}


\hypertarget{DynamicArray_8h_fa79a315bde67685f9fc5916481d6187}{
\index{DynamicArray.h@{DynamicArray.h}!SetElement@{SetElement}}
\index{SetElement@{SetElement}!DynamicArray.h@{DynamicArray.h}}
\subsubsection[{SetElement}]{\setlength{\rightskip}{0pt plus 5cm}int SetElement (D\_\-Array {\em array}, \/  unsigned int {\em n}, \/  void $\ast$ {\em element})}}
\label{DynamicArray_8h_fa79a315bde67685f9fc5916481d6187}


Set an element of a dynamic array to a supplied value.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em array}]the array to operate on \item[{\em n}]the position of the element to set \item[{\em element}]a pointer to the element to set\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 on success, -errno on failure \end{Desc}


Definition at line 156 of file DynamicArray.c.

\begin{Code}\begin{verbatim}157 {
158 
159   /* Grow the array if we need to, dying if we can't, and updating the
160      length. */
161   if( n > array -> max_length )
162     {
163 
164       if( !( array -> array = realloc( array -> array , n + 1 ) ) )
165     return( -errno ) ;
166 
167       array -> max_length = array -> length = n + 1 ;
168 
169     }
170 
171   /* Copy the element into the right place */
172   array -> array[ n ] = element ;
173 
174   /* Success, so return so */
175   return( 0 ) ;
176 
177 }
\end{verbatim}
\end{Code}


